<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>gdbus-codegen: GIO Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="GIO Reference Manual">
<link rel="up" href="tools.html" title="GIO Tools">
<link rel="prev" href="gdbus.html" title="gdbus">
<link rel="next" href="gresource-tool.html" title="gresource">
<meta name="generator" content="GTK-Doc V1.26.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="tools.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="gdbus.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="gresource-tool.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div lang="en" class="refentry">
<a name="gdbus-codegen"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">gdbus-codegen</span></h2>
<p>gdbus-codegen — D-Bus code and documentation generator</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis"><p><code class="command">gdbus-codegen</code>  [<code class="option">-h</code>, <code class="option">--help</code>] [<code class="option">--interface-prefix</code> <em class="replaceable"><code>org.project.Prefix</code></em>] [<code class="option">--generate-c-code</code> <em class="replaceable"><code>OUTFILES</code></em>] [<code class="option">--c-namespace</code> <em class="replaceable"><code>YourProject</code></em>] [<code class="option">--c-generate-object-manager</code>] [<code class="option">--c-generate-autocleanup</code> none|objects|all] [<code class="option">--output-directory</code> <em class="replaceable"><code>OUTDIR</code></em>] [<code class="option">--generate-docbook</code> <em class="replaceable"><code>OUTFILES</code></em>] [<code class="option">--xml-files</code> <em class="replaceable"><code>FILE</code></em>]  [
        <code class="option">--annotate</code>
        <em class="replaceable"><code>ELEMENT</code></em>
        <em class="replaceable"><code>KEY</code></em>
        <em class="replaceable"><code>VALUE</code></em>
      ]...   FILE  [
       FILE... 
    ]</p></div>
</div>
<div class="refsect1">
<a name="id-1.4.26.7.5"></a><h2>Description</h2>
<p>
    <span class="command"><strong>gdbus-codegen</strong></span> is used to generate code and/or
    documentation for one or more D-Bus interfaces. The tool reads
    <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format" target="_top">D-Bus
    Introspection XML</a> files and generates output files. The
    tool currently supports generating C code (via
    <code class="option">--generate-c-code</code>) and Docbook XML (via
    <code class="option">--generate-docbook</code>).
  </p>
</div>
<div class="refsect1">
<a name="id-1.4.26.7.6"></a><h2>Generating C code</h2>
<p>
    When generating C code, a
    <a href="/home/mclasen/gnome/share/gtk-doc/html/gobject/GTypeModule.html"><span class="type">GInterface</span></a>-derived type is generated for each D-Bus
    interface. Additionally, for every generated type,
    <span class="type">FooBar</span>, two concrete instantiable types,
    <span class="type">FooBarProxy</span> and <span class="type">FooBarSkeleton</span>, implementing
    said interface are also generated. The former is derived from
    <a class="link" href="GDBusProxy.html" title="GDBusProxy"><span class="type">GDBusProxy</span></a> and intended for use on the client side
    while the latter is derived from the
    <a class="link" href="GDBusInterfaceSkeleton.html" title="GDBusInterfaceSkeleton"><span class="type">GDBusInterfaceSkeleton</span></a> type making it easy to export on a
    <a class="link" href="GDBusConnection.html" title="GDBusConnection"><span class="type">GDBusConnection</span></a> either directly or via a
    <a class="link" href="GDBusObjectManagerServer.html" title="GDBusObjectManagerServer"><span class="type">GDBusObjectManagerServer</span></a> instance.
  </p>
<p>
    The name of each generated C type is derived from the D-Bus
    interface name stripped with the prefix given with
    <code class="option">--interface-prefix</code> and with the dots removed and
    initial characters capitalized. For example, for the D-Bus
    interface <code class="literal">com.acme.Coyote</code> the name used is
    <code class="literal">ComAcmeCoyote</code>. For the D-Bus interface
    <code class="literal">org.project.Bar.Frobnicator</code> with
    <code class="option">--interface-prefix</code>
    <code class="literal">org.project.</code>, the name used is
    <code class="literal">BarFrobnicator</code>.
  </p>
<p>
    For methods, signals and properties, if not specified, the name
    defaults to the name of the method, signal or property.
  </p>
<p>
    Two forms of the name are used - the CamelCase form and the
    lower-case form. The CamelCase form is used for the <a href="../gobject-Type-Information.html#GType"><span class="type">GType</span></a> and
    struct name, while lower-case form is used in function names. The
    lower-case form is calculated by converting from CamelCase to
    lower-case and inserting underscores at word boundaries (using
    certain heuristics).
  </p>
<p>
    If the value given by the <code class="literal">org.gtk.GDBus.C.Name</code>
    annotation or the <code class="option">--c-namespace</code> option contains
    an underscore (sometimes called <span class="emphasis"><em>Ugly_Case</em></span>),
    then the camel-case name is derived by removing all underscores,
    and the lower-case name is derived by lower-casing the
    string. This is useful in some situations where abbreviations are
    used. For example, if the annotation is used on the interface
    <code class="literal">net.MyCorp.MyApp.iSCSITarget</code> with the value
    <code class="literal">iSCSI_Target</code> the CamelCase form is
    <code class="literal">iSCSITarget</code> while the lower-case form is
    <code class="literal">iscsi_target</code>. If the annotation is used on the
    method <code class="literal">EjectTheiPod</code> with the value
    <code class="literal">Eject_The_iPod</code>, the lower-case form is
    <code class="literal">eject_the_ipod</code>.
  </p>
</div>
<div class="refsect1">
<a name="id-1.4.26.7.7"></a><h2>Generating Docbook documentation</h2>
<p>
    Each generated Docbook XML file (see the
    <code class="option">--generate-docbook</code> option for details) is a <a class="ulink" href="http://www.docbook.org/tdg/en/html/refentry.html" target="_top"><code class="literal">RefEntry</code></a>
    article describing the D-Bus interface.
  </p>
</div>
<div class="refsect1">
<a name="id-1.4.26.7.8"></a><h2>Options</h2>
<p>
    The following options are supported:
  </p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="option">-h</code>, <code class="option">--help</code></span></p></td>
<td><p>
          Show help and exit.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">--xml-files</code> <em class="replaceable"><code>FILE</code></em></span></p></td>
<td><p>
          The D-Bus introspection XML file.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">--interface-prefix</code> <em class="replaceable"><code>org.project.Prefix.</code></em></span></p></td>
<td><p>
          A prefix to strip from all D-Bus interface names when
          calculating the typename for the C binding and the Docbook
          <a class="ulink" href="http://www.docbook.org/tdg/en/html/primary.html" target="_top">sortas
          attribute</a>.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">--generate-docbook</code> <em class="replaceable"><code>OUTFILES</code></em></span></p></td>
<td><p>
          Generate Docbook Documentation for each D-Bus interface and
          put it in <code class="filename">OUTFILES-NAME.xml</code> where
          <code class="literal">NAME</code> is a place-holder for the interface
          name, e.g. <code class="literal">net.Corp.FooBar</code> and so on.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">--generate-c-code</code> <em class="replaceable"><code>OUTFILES</code></em></span></p></td>
<td>
<p>
          Generate C code for all D-Bus interfaces and put it in
          <code class="filename">OUTFILES.c</code> and
          <code class="filename">OUTFILES.h</code> including any sub-directories. If you want the files to
          be output in a different location use <code class="option">--output-directory</code> as <code class="filename">OUTFILES.h</code>
          including sub-directories will be referenced from <code class="filename">OUTFILES.c</code>.
        </p>
<p>
          The full paths would then be <code class="literal">$(OUTDIR)/$(dirname $OUTFILES)/$(basename $OUTFILES).{c,h}</code>.
        </p>
</td>
</tr>
<tr>
<td><p><span class="term"><code class="option">--c-namespace</code> <em class="replaceable"><code>YourProject</code></em></span></p></td>
<td><p>
          The namespace to use for generated C code. This is expected
          to be in <a class="ulink" href="http://en.wikipedia.org/wiki/CamelCase" target="_top">CamelCase</a>
          or <span class="emphasis"><em>Ugly_Case</em></span> (see above).
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">--c-generate-object-manager</code></span></p></td>
<td><p>
          If this option is passed, suitable <a class="link" href="GDBusObject.html" title="GDBusObject"><span class="type">GDBusObject</span></a>,
          <a class="link" href="GDBusObjectProxy.html" title="GDBusObjectProxy"><span class="type">GDBusObjectProxy</span></a>, <a class="link" href="GDBusObjectSkeleton.html" title="GDBusObjectSkeleton"><span class="type">GDBusObjectSkeleton</span></a> and
          <a class="link" href="GDBusObjectManagerClient.html" title="GDBusObjectManagerClient"><span class="type">GDBusObjectManagerClient</span></a> subclasses are generated.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">--c-generate-autocleanup</code> none|objects|all</span></p></td>
<td><p>
          This option influences what types autocleanup functions are
          generated for. 'none' means to not generate any autocleanup functions.
          'objects' means to generate them for object types, and 'all' means to
          generate them for object types and interfaces. The default is 'objects'
          due to a corner case in backwards compatibility with a few projects,
          but you should likely switch your project to use 'all'.
          This option was added in GLib 2.50.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">--output-directory</code> <em class="replaceable"><code>OUTDIR</code></em></span></p></td>
<td><p>
          Directory to output generated source to. Equivalent to changing directory before generation.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="option">--annotate</code> <em class="replaceable"><code>ELEMENT</code></em> <em class="replaceable"><code>KEY</code></em> <em class="replaceable"><code>VALUE</code></em></span></p></td>
<td>
<p>
          Used to inject D-Bus annotations into the given XML
          files. It can be used with interfaces, methods, signals,
          properties and arguments in the following way:
        </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15</pre></td>
        <td class="listing_code"><pre class="programlisting">gdbus<span class="gtkdoc opt">-</span>codegen <span class="gtkdoc opt">--</span>c<span class="gtkdoc opt">-</span><span class="keyword">namespace</span> MyApp                           \
  <span class="gtkdoc opt">--</span>generate<span class="gtkdoc opt">-</span>c<span class="gtkdoc opt">-</span>code myapp<span class="gtkdoc opt">-</span>generated                         \
  <span class="gtkdoc opt">--</span>annotate <span class="string">&quot;org.project.InterfaceName&quot;</span>                    \
    org<span class="gtkdoc opt">.</span>gtk<span class="gtkdoc opt">.</span>GDBus<span class="gtkdoc opt">.</span>C<span class="gtkdoc opt">.</span>Name MyFrobnicator                      \
  <span class="gtkdoc opt">--</span>annotate <span class="string">&quot;org.project.InterfaceName:Property&quot;</span>           \
    bar bat                                                 \
  <span class="gtkdoc opt">--</span>annotate <span class="string">&quot;org.project.InterfaceName.Method()&quot;</span>           \
    org<span class="gtkdoc opt">.</span>freedesktop<span class="gtkdoc opt">.</span>DBus<span class="gtkdoc opt">.</span>Deprecated <span class="keyword">true</span>                    \
  <span class="gtkdoc opt">--</span>annotate <span class="string">&quot;org.project.InterfaceName.Method()[arg_name]&quot;</span> \
    snake hiss                                              \
  <span class="gtkdoc opt">--</span>annotate <span class="string">&quot;org.project.InterfaceName::Signal&quot;</span>            \
    cat meow                                                \
  <span class="gtkdoc opt">--</span>annotate <span class="string">&quot;org.project.InterfaceName::Signal[arg_name]&quot;</span>  \
    dog wuff                                                \
  myapp<span class="gtkdoc opt">-</span>dbus<span class="gtkdoc opt">-</span>interfaces<span class="gtkdoc opt">.</span>xml</pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
          Any UTF-8 string can be used for <em class="replaceable"><code>KEY</code></em> and <em class="replaceable"><code>VALUE</code></em>.
        </p>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="id-1.4.26.7.9"></a><h2>Supported D-Bus Annotations</h2>
<p>
    The following D-Bus annotations are supported by
    <span class="command"><strong>gdbus-codegen</strong></span>:
  </p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="literal">org.freedesktop.DBus.Deprecated</code></span></p></td>
<td>
<p>
          Can be used on any <code class="literal">&lt;interface&gt;</code>,
          <code class="literal">&lt;method&gt;</code>,
          <code class="literal">&lt;signal&gt;</code> and
          <code class="literal">&lt;property&gt;</code> element to specify that
          the element is deprecated if its value is
          <code class="literal">true</code>. Note that this annotation is
          defined in the <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format" target="_top">D-Bus
          specification</a> and can only assume the values
          <code class="literal">true</code> and <code class="literal">false</code>. In
          particular, you cannot specify the version that the element
          was deprecated in nor any helpful deprecation message. Such
          information should be added to the element documentation
          instead.
        </p>
<p>
          When generating C code, this annotation is used to add
          <a href="../glib-Miscellaneous-Macros.html#G-GNUC-DEPRECATED:CAPS"><span class="type">G_GNUC_DEPRECATED</span></a> to generated functions for the element.
        </p>
<p>
          When generating Docbook XML, a deprecation warning will
          appear along the documentation for the element.
        </p>
</td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">org.gtk.GDBus.Since</code></span></p></td>
<td>
<p>
          Can be used on any <code class="literal">&lt;interface&gt;</code>,
          <code class="literal">&lt;method&gt;</code>,
          <code class="literal">&lt;signal&gt;</code> and
          <code class="literal">&lt;property&gt;</code> element to specify the
          version (any free-form string but compared using a
          version-aware sort function) the element appeared in.
        </p>
<p>
          When generating C code, this field is used to ensure
          function pointer order for preserving ABI/API, see <a class="xref" href="gdbus-codegen.html#gdbus-code-stability" title="Stability Guarantees">the section called “Stability Guarantees”</a>.
        </p>
<p>
          When generating Docbook XML, the value of this tag appears
          in the documentation.
        </p>
</td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">org.gtk.GDBus.DocString</code></span></p></td>
<td><p>
          A string with Docbook content for documentation. This annotation can
          be used on <code class="literal">&lt;interface&gt;</code>,
          <code class="literal">&lt;method&gt;</code>,
          <code class="literal">&lt;signal&gt;</code>,
          <code class="literal">&lt;property&gt;</code> and
          <code class="literal">&lt;arg&gt;</code> elements.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">org.gtk.GDBus.DocString.Short</code></span></p></td>
<td><p>
          A string with Docbook content for short/brief
          documentation. This annotation can only be used on
          <code class="literal">&lt;interface&gt;</code> elements.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">org.gtk.GDBus.C.Name</code></span></p></td>
<td><p>
          Can be used on any <code class="literal">&lt;interface&gt;</code>,
          <code class="literal">&lt;method&gt;</code>,
          <code class="literal">&lt;signal&gt;</code> and
          <code class="literal">&lt;property&gt;</code> element to specify the
          name to use when generating C code. The value is expected to
          be in <a class="ulink" href="http://en.wikipedia.org/wiki/CamelCase" target="_top">CamelCase</a>
          or <span class="emphasis"><em>Ugly_Case</em></span> (see above).
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">org.gtk.GDBus.C.ForceGVariant</code></span></p></td>
<td><p>
          If set to a non-empty string, a <a href="../glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> instance will
          be used instead of the natural C type. This annotation can
          be used on any <code class="literal">&lt;arg&gt;</code> and
          <code class="literal">&lt;property&gt;</code> element.
        </p></td>
</tr>
<tr>
<td><p><span class="term"><code class="literal">org.gtk.GDBus.C.UnixFD</code></span></p></td>
<td><p>
          If set to a non-empty string, the generated code will
          include parameters to exchange file descriptors using the
          <a class="link" href="GUnixFDList.html" title="GUnixFDList"><span class="type">GUnixFDList</span></a> type. This annotation can be used on
          <code class="literal">&lt;method&gt;</code> elements.
        </p></td>
</tr>
</tbody>
</table></div>
<p>
    As an easier alternative to using the
    <code class="literal">org.gtk.GDBus.DocString</code> annotation, note that
    parser used by <span class="command"><strong>gdbus-codegen</strong></span> parses XML
    comments in a way similar to <a class="ulink" href="http://www.gtk.org/gtk-doc/" target="_top">gtk-doc</a>:
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="gtkdoc opt">&lt;!--</span>
  net<span class="gtkdoc opt">.</span>Corp<span class="gtkdoc opt">.</span>Bar<span class="gtkdoc opt">:</span>
  &#64;short_description<span class="gtkdoc opt">:</span> A <span class="gtkdoc kwb">short</span> description

  A <span class="gtkdoc opt">&lt;</span>emphasis<span class="gtkdoc opt">&gt;</span>longer<span class="gtkdoc opt">&lt;/</span>emphasis<span class="gtkdoc opt">&gt;</span> description<span class="gtkdoc opt">.</span>

  This is a <span class="keyword">new</span> paragraph<span class="gtkdoc opt">.</span>
<span class="gtkdoc opt">--&gt;</span>
<span class="gtkdoc opt">&lt;</span>interface name<span class="gtkdoc opt">=</span><span class="string">&quot;net.corp.Bar&quot;</span><span class="gtkdoc opt">&gt;</span>
  <span class="gtkdoc opt">&lt;!--</span>
    FooMethod<span class="gtkdoc opt">:</span>
    &#64;greeting<span class="gtkdoc opt">:</span> The docs <span class="keyword">for</span> greeting parameter<span class="gtkdoc opt">.</span>
    &#64;response<span class="gtkdoc opt">:</span> The docs <span class="keyword">for</span> response parameter<span class="gtkdoc opt">.</span>

    The docs <span class="keyword">for</span> the actual method<span class="gtkdoc opt">.</span>
  <span class="gtkdoc opt">--&gt;</span>
  <span class="gtkdoc opt">&lt;</span>method name<span class="gtkdoc opt">=</span><span class="string">&quot;FooMethod&quot;</span><span class="gtkdoc opt">&gt;</span>
    <span class="gtkdoc opt">&lt;</span>arg name<span class="gtkdoc opt">=</span><span class="string">&quot;greeting&quot;</span> direction<span class="gtkdoc opt">=</span><span class="string">&quot;in&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;s&quot;</span><span class="gtkdoc opt">/&gt;</span>
    <span class="gtkdoc opt">&lt;</span>arg name<span class="gtkdoc opt">=</span><span class="string">&quot;response&quot;</span> direction<span class="gtkdoc opt">=</span><span class="string">&quot;out&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;s&quot;</span><span class="gtkdoc opt">/&gt;</span>
  <span class="gtkdoc opt">&lt;/</span>method<span class="gtkdoc opt">&gt;</span>

  <span class="gtkdoc opt">&lt;!--</span>
    BarSignal<span class="gtkdoc opt">:</span>
    &#64;blah<span class="gtkdoc opt">:</span> The docs <span class="keyword">for</span> blah parameter<span class="gtkdoc opt">.</span>
    &#64;boo<span class="gtkdoc opt">:</span> The docs <span class="keyword">for</span> boo parameter<span class="gtkdoc opt">.</span>
    &#64;since<span class="gtkdoc opt">:</span> <span class="number">2.30</span>

    The docs <span class="keyword">for</span> the actual signal<span class="gtkdoc opt">.</span>
  <span class="gtkdoc opt">--&gt;</span>
  <span class="gtkdoc opt">&lt;</span>signal name<span class="gtkdoc opt">=</span><span class="string">&quot;BarSignal&quot;</span><span class="gtkdoc opt">&gt;</span>
    <span class="gtkdoc opt">&lt;</span>arg name<span class="gtkdoc opt">=</span><span class="string">&quot;blah&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;s&quot;</span><span class="gtkdoc opt">/&gt;</span>
    <span class="gtkdoc opt">&lt;</span>arg name<span class="gtkdoc opt">=</span><span class="string">&quot;boo&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;s&quot;</span><span class="gtkdoc opt">/&gt;</span>
  <span class="gtkdoc opt">&lt;/</span>signal<span class="gtkdoc opt">&gt;</span>

  <span class="gtkdoc opt">&lt;!--</span> BazProperty<span class="gtkdoc opt">:</span> The docs <span class="keyword">for</span> the property<span class="gtkdoc opt">. --&gt;</span>
  <span class="gtkdoc opt">&lt;</span>property name<span class="gtkdoc opt">=</span><span class="string">&quot;BazProperty&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;s&quot;</span> access<span class="gtkdoc opt">=</span><span class="string">&quot;read&quot;</span><span class="gtkdoc opt">/&gt;</span>
<span class="gtkdoc opt">&lt;/</span>interface<span class="gtkdoc opt">&gt;</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
  </p>
<p>
    Note that <code class="literal">&lt;parameter&gt;since&lt;/parameter&gt;</code> can be used in any inline
    documentation bit (e.g. for interfaces, methods, signals and
    properties) to set the <code class="literal">org.gtk.GDBus.Since</code>
    annotation. For the <code class="literal">org.gtk.GDBus.DocString</code>
    annotation (and inline comments), note that substrings of the form
    <code class="literal">&lt;link linkend="net.Corp.Bar"&gt;&lt;type&gt;net.Corp.Bar&lt;/type&gt;&lt;/link&gt;</code>,
    <code class="literal">net.Corp.Bar.FooMethod()</code>,
    <code class="literal">&lt;link linkend="net.Corp.Bar-BarSignal"&gt;&lt;type&gt;“BarSignal”&lt;/type&gt;&lt;/link&gt;</code> and
    <code class="literal">&lt;link linkend="net.Corp.InlineDocs--BazProperty"&gt;&lt;type&gt;“BazProperty”&lt;/type&gt;&lt;/link&gt;</code> are all
    expanded to links to the respective interface, method, signal and
    property.
    Additionally, substrings starting with <code class="literal">@</code> and <code class="literal">%</code> characters are rendered as
    <a class="ulink" href="http://www.docbook.org/tdg/en/html/parameter.html" target="_top">parameter</a> and
    <a class="ulink" href="http://www.docbook.org/tdg/en/html/constant.html" target="_top">constant</a> respectively.
  </p>
<p>
    If both XML comments and
    <code class="literal">org.gtk.GDBus.DocString</code> or
    <code class="literal">org.gtk.GDBus.DocString.Short</code> annotations are
    present, the latter wins.
  </p>
</div>
<div class="refsect1">
<a name="id-1.4.26.7.10"></a><h2>Example</h2>
<p>
    Consider the following D-Bus Introspection XML.
  </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="gtkdoc opt">&lt;</span>node<span class="gtkdoc opt">&gt;</span>
  <span class="gtkdoc opt">&lt;</span>interface name<span class="gtkdoc opt">=</span><span class="string">&quot;net.Corp.MyApp.Frobber&quot;</span><span class="gtkdoc opt">&gt;</span>
    <span class="gtkdoc opt">&lt;</span>method name<span class="gtkdoc opt">=</span><span class="string">&quot;HelloWorld&quot;</span><span class="gtkdoc opt">&gt;</span>
      <span class="gtkdoc opt">&lt;</span>arg name<span class="gtkdoc opt">=</span><span class="string">&quot;greeting&quot;</span> direction<span class="gtkdoc opt">=</span><span class="string">&quot;in&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;s&quot;</span><span class="gtkdoc opt">/&gt;</span>
      <span class="gtkdoc opt">&lt;</span>arg name<span class="gtkdoc opt">=</span><span class="string">&quot;response&quot;</span> direction<span class="gtkdoc opt">=</span><span class="string">&quot;out&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;s&quot;</span><span class="gtkdoc opt">/&gt;</span>
    <span class="gtkdoc opt">&lt;/</span>method<span class="gtkdoc opt">&gt;</span>

    <span class="gtkdoc opt">&lt;</span>signal name<span class="gtkdoc opt">=</span><span class="string">&quot;Notification&quot;</span><span class="gtkdoc opt">&gt;</span>
      <span class="gtkdoc opt">&lt;</span>arg name<span class="gtkdoc opt">=</span><span class="string">&quot;icon_blob&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;ay&quot;</span><span class="gtkdoc opt">/&gt;</span>
      <span class="gtkdoc opt">&lt;</span>arg name<span class="gtkdoc opt">=</span><span class="string">&quot;height&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;i&quot;</span><span class="gtkdoc opt">/&gt;</span>
      <span class="gtkdoc opt">&lt;</span>arg name<span class="gtkdoc opt">=</span><span class="string">&quot;messages&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;as&quot;</span><span class="gtkdoc opt">/&gt;</span>
    <span class="gtkdoc opt">&lt;/</span>signal<span class="gtkdoc opt">&gt;</span>

    <span class="gtkdoc opt">&lt;</span>property name<span class="gtkdoc opt">=</span><span class="string">&quot;Verbose&quot;</span> type<span class="gtkdoc opt">=</span><span class="string">&quot;b&quot;</span> access<span class="gtkdoc opt">=</span><span class="string">&quot;readwrite&quot;</span><span class="gtkdoc opt">/&gt;</span>
  <span class="gtkdoc opt">&lt;/</span>interface<span class="gtkdoc opt">&gt;</span>
<span class="gtkdoc opt">&lt;/</span>node<span class="gtkdoc opt">&gt;</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
    If <span class="command"><strong>gdbus-codegen</strong></span> is used on this file like this:
  </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4</pre></td>
        <td class="listing_code"><pre class="programlisting">gdbus<span class="gtkdoc opt">-</span>codegen <span class="gtkdoc opt">--</span>generate<span class="gtkdoc opt">-</span>c<span class="gtkdoc opt">-</span>code myapp<span class="gtkdoc opt">-</span>generated       \
              <span class="gtkdoc opt">--</span>c<span class="gtkdoc opt">-</span><span class="keyword">namespace</span> MyApp                     \
              <span class="gtkdoc opt">--</span>interface<span class="gtkdoc opt">-</span>prefix net<span class="gtkdoc opt">.</span>corp<span class="gtkdoc opt">.</span>MyApp<span class="gtkdoc opt">.</span>      \
              net<span class="gtkdoc opt">.</span>Corp<span class="gtkdoc opt">.</span>MyApp<span class="gtkdoc opt">.</span>Frobber<span class="gtkdoc opt">.</span>xml</pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
    two files called
    <code class="filename">myapp-generated.[ch]</code> are
    generated. The files provide an abstract
    <a href="../gobject-Type-Information.html#GTypeInterface"><span class="type">GTypeInterface</span></a>-derived type called
    <span class="type">MyAppFrobber</span> as well as two instantiable types with
    the same name but suffixed with <span class="type">Proxy</span> and
    <span class="type">Skeleton</span>. The generated file, roughly, contains the
    following facilities:
  </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="comment">/* GType macros for the three generated types */</span>
<span class="gtkdoc ppc">#define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())</span>
<span class="gtkdoc ppc">#define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())</span>
<span class="gtkdoc ppc">#define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())</span>

<span class="gtkdoc kwc">typedef</span> <span class="gtkdoc kwb">struct</span> _MyAppFrobber MyAppFrobber<span class="gtkdoc opt">;</span> <span class="comment">/* Dummy typedef */</span>

<span class="gtkdoc kwc">typedef</span> <span class="gtkdoc kwb">struct</span>
<span class="gtkdoc opt">{</span>
  GTypeInterface parent_iface<span class="gtkdoc opt">;</span>

  <span class="comment">/* Signal handler for the ::notification signal */</span>
  <span class="gtkdoc kwb">void</span> <span class="gtkdoc opt">(*</span>notification<span class="gtkdoc opt">) (</span>MyAppFrobber <span class="gtkdoc opt">*</span>proxy<span class="gtkdoc opt">,</span>
                        GVariant <span class="gtkdoc opt">*</span>icon_blob<span class="gtkdoc opt">,</span>
                        gint height<span class="gtkdoc opt">,</span>
                        <span class="gtkdoc kwb">const</span> gchar<span class="gtkdoc opt">*</span> <span class="gtkdoc kwb">const</span> <span class="gtkdoc opt">*</span>messages<span class="gtkdoc opt">);</span>

  <span class="comment">/* Signal handler for the ::handle-hello-world signal */</span>
  <span class="function"><a href="../glib-Basic-Types.html#gboolean">gboolean</a></span> <span class="gtkdoc opt">(*</span>handle_hello_world<span class="gtkdoc opt">) (</span>MyAppFrobber <span class="gtkdoc opt">*</span>proxy<span class="gtkdoc opt">,</span>
                                  GDBusMethodInvocation <span class="gtkdoc opt">*</span>invocation<span class="gtkdoc opt">,</span>
                                  <span class="gtkdoc kwb">const</span> gchar <span class="gtkdoc opt">*</span>greeting<span class="gtkdoc opt">);</span>
<span class="gtkdoc opt">}</span> MyAppFrobberIface<span class="gtkdoc opt">;</span>

<span class="comment">/* Asynchronously calls HelloWorld() */</span>
<span class="gtkdoc kwb">void</span>
<span class="function">my_app_frobber_call_hello_world</span> <span class="gtkdoc opt">(</span>MyAppFrobber <span class="gtkdoc opt">*</span>proxy<span class="gtkdoc opt">,</span>
                                 <span class="gtkdoc kwb">const</span> gchar <span class="gtkdoc opt">*</span>greeting<span class="gtkdoc opt">,</span>
                                 GCancellable <span class="gtkdoc opt">*</span>cancellable<span class="gtkdoc opt">,</span>
                                 GAsyncReadyCallback callback<span class="gtkdoc opt">,</span>
                                 gpointer user_data<span class="gtkdoc opt">);</span>
gboolean
<span class="function">my_app_frobber_call_hello_world_finish</span> <span class="gtkdoc opt">(</span>MyAppFrobber <span class="gtkdoc opt">*</span>proxy<span class="gtkdoc opt">,</span>
                                        gchar <span class="gtkdoc opt">**</span>out_response<span class="gtkdoc opt">,</span>
                                        GAsyncResult <span class="gtkdoc opt">*</span>res<span class="gtkdoc opt">,</span>
                                        GError <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">);</span>

<span class="comment">/* Synchronously calls HelloWorld(). Blocks calling thread. */</span>
gboolean
<span class="function">my_app_frobber_call_hello_world_sync</span> <span class="gtkdoc opt">(</span>MyAppFrobber <span class="gtkdoc opt">*</span>proxy<span class="gtkdoc opt">,</span>
                                      <span class="gtkdoc kwb">const</span> gchar <span class="gtkdoc opt">*</span>greeting<span class="gtkdoc opt">,</span>
                                      gchar <span class="gtkdoc opt">**</span>out_response<span class="gtkdoc opt">,</span>
                                      GCancellable <span class="gtkdoc opt">*</span>cancellable<span class="gtkdoc opt">,</span>
                                      GError <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">);</span>

<span class="comment">/* Completes handling the HelloWorld() method call */</span>
<span class="gtkdoc kwb">void</span>
<span class="function">my_app_frobber_complete_hello_world</span> <span class="gtkdoc opt">(</span>MyAppFrobber <span class="gtkdoc opt">*</span>object<span class="gtkdoc opt">,</span>
                                     GDBusMethodInvocation <span class="gtkdoc opt">*</span>invocation<span class="gtkdoc opt">,</span>
                                     <span class="gtkdoc kwb">const</span> gchar <span class="gtkdoc opt">*</span>response<span class="gtkdoc opt">);</span>

<span class="comment">/* Emits the ::notification signal / Notification() D-Bus signal */</span>
<span class="gtkdoc kwb">void</span>
<span class="function">my_app_frobber_emit_notification</span> <span class="gtkdoc opt">(</span>MyAppFrobber <span class="gtkdoc opt">*</span>object<span class="gtkdoc opt">,</span>
                                  GVariant <span class="gtkdoc opt">*</span>icon_blob<span class="gtkdoc opt">,</span>
                                  gint height<span class="gtkdoc opt">,</span>
                                  <span class="gtkdoc kwb">const</span> gchar<span class="gtkdoc opt">*</span> <span class="gtkdoc kwb">const</span> <span class="gtkdoc opt">*</span>messages<span class="gtkdoc opt">);</span>

<span class="comment">/* Gets the :verbose GObject property / Verbose D-Bus property.</span>
<span class="comment"> * Does no blocking I/O.</span>
<span class="comment"> */</span>
gboolean <span class="function">my_app_frobber_get_verbose</span> <span class="gtkdoc opt">(</span>MyAppFrobber <span class="gtkdoc opt">*</span>object<span class="gtkdoc opt">);</span>

<span class="comment">/* Sets the :verbose GObject property / Verbose D-Bus property.</span>
<span class="comment"> * Does no blocking I/O.</span>
<span class="comment"> */</span>
<span class="gtkdoc kwb">void</span> <span class="function">my_app_frobber_set_verbose</span> <span class="gtkdoc opt">(</span>MyAppFrobber <span class="gtkdoc opt">*</span>object<span class="gtkdoc opt">,</span>
                                 gboolean      value<span class="gtkdoc opt">);</span>

<span class="comment">/* Gets the interface info */</span>
GDBusInterfaceInfo <span class="gtkdoc opt">*</span><span class="function">my_app_frobber_interface_info</span> <span class="gtkdoc opt">(</span><span class="gtkdoc kwb">void</span><span class="gtkdoc opt">);</span>

<span class="comment">/* Creates a new skeleton object, ready to be exported */</span>
MyAppFrobber <span class="gtkdoc opt">*</span><span class="function">my_app_frobber_skeleton_new</span> <span class="gtkdoc opt">(</span><span class="gtkdoc kwb">void</span><span class="gtkdoc opt">);</span>

<span class="comment">/* Client-side proxy constructors.</span>
<span class="comment"> *</span>
<span class="comment"> * Additionally, _new_for_bus(), _new_for_bus_finish() and</span>
<span class="comment"> * _new_for_bus_sync() proxy constructors are also generated.</span>
<span class="comment"> */</span>
<span class="gtkdoc kwb">void</span>
<span class="function">my_app_frobber_proxy_new</span>        <span class="gtkdoc opt">(</span>GDBusConnection     <span class="gtkdoc opt">*</span>connection<span class="gtkdoc opt">,</span>
                                 GDBusProxyFlags      flags<span class="gtkdoc opt">,</span>
                                 <span class="gtkdoc kwb">const</span> gchar         <span class="gtkdoc opt">*</span>name<span class="gtkdoc opt">,</span>
                                 <span class="gtkdoc kwb">const</span> gchar         <span class="gtkdoc opt">*</span>object_path<span class="gtkdoc opt">,</span>
                                 GCancellable        <span class="gtkdoc opt">*</span>cancellable<span class="gtkdoc opt">,</span>
                                 GAsyncReadyCallback  callback<span class="gtkdoc opt">,</span>
                                 gpointer             user_data<span class="gtkdoc opt">);</span>
MyAppFrobber <span class="gtkdoc opt">*</span>
<span class="function">my_app_frobber_proxy_new_finish</span> <span class="gtkdoc opt">(</span>GAsyncResult        <span class="gtkdoc opt">*</span>res<span class="gtkdoc opt">,</span>
                                 GError             <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">);</span>
MyAppFrobber <span class="gtkdoc opt">*</span>
<span class="function">my_app_frobber_proxy_new_sync</span>   <span class="gtkdoc opt">(</span>GDBusConnection     <span class="gtkdoc opt">*</span>connection<span class="gtkdoc opt">,</span>
                                 GDBusProxyFlags      flags<span class="gtkdoc opt">,</span>
                                 <span class="gtkdoc kwb">const</span> gchar         <span class="gtkdoc opt">*</span>name<span class="gtkdoc opt">,</span>
                                 <span class="gtkdoc kwb">const</span> gchar         <span class="gtkdoc opt">*</span>object_path<span class="gtkdoc opt">,</span>
                                 GCancellable        <span class="gtkdoc opt">*</span>cancellable<span class="gtkdoc opt">,</span>
                                 GError             <span class="gtkdoc opt">**</span>error<span class="gtkdoc opt">);</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
    Thus, for every D-Bus method, there will be three C functions for
    calling the method, one <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a> signal for handling an incoming
    call and one C function for completing an incoming call. For every
    D-Bus signal, there's one <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a> signal and one C function for
    emitting it. For every D-Bus property, two C functions are
    generated (one setter, one getter) and one <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a> property. The
    following table summarizes the generated facilities and where they
    are applicable:
  </p>
<div class="informaltable"><table class="informaltable" border="1">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th> </th>
<th>Client</th>
<th>Server</th>
</tr></thead>
<tbody>
<tr>
<td>Types</td>
<td>Use <span class="type">MyAppFrobberProxy</span>
</td>
<td>Any type implementing the <span class="type">MyAppFrobber</span> interface</td>
</tr>
<tr>
<td>Methods</td>
<td>Use <code class="function"><code class="function">m_a_f_hello_world()</code></code> to call.</td>
<td>Receive via the <code class="function"><code class="function">handle_hello_world()</code></code> signal handler. Complete the call with <code class="function"><code class="function">m_a_f_complete_hello_world()</code></code>
</td>
</tr>
<tr>
<td>Signals</td>
<td>Connect to the <code class="function">::notification</code> GObject signal.</td>
<td>Use <code class="function"><code class="function">m_a_f_emit_notification()</code></code> to emit signal.</td>
</tr>
<tr>
<td>Properties (Reading)</td>
<td>Use <code class="function"><code class="function">m_a_f_get_verbose()</code></code> or <em class="parameter"><code>:verbose</code></em>.</td>
<td>Implement <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a>'s <code class="function"><code class="function">get_property()</code></code> vfunc.</td>
</tr>
<tr>
<td>Properties (writing)</td>
<td>Use <code class="function"><code class="function">m_a_f_set_verbose()</code></code> or <em class="parameter"><code>:verbose</code></em>.</td>
<td>Implement <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a>'s <code class="function"><code class="function">set_property()</code></code> vfunc.</td>
</tr>
</tbody>
</table></div>
<div class="refsect2">
<a name="id-1.4.26.7.10.10"></a><h3>Client-side usage</h3>
<p>
      You can use the generated proxy type with the generated
      constructors:
    </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13</pre></td>
        <td class="listing_code"><pre class="programlisting">MyAppFrobber <span class="gtkdoc opt">*</span>proxy<span class="gtkdoc opt">;</span>
GError <span class="gtkdoc opt">*</span>error<span class="gtkdoc opt">;</span>

error <span class="gtkdoc opt">=</span> NULL<span class="gtkdoc opt">;</span>
proxy <span class="gtkdoc opt">=</span> <span class="function">my_app_frobber_proxy_new_for_bus_sync</span> <span class="gtkdoc opt">(</span>
            G_BUS_TYPE_SESSION<span class="gtkdoc opt">,</span>
            G_DBUS_PROXY_FLAGS_NONE<span class="gtkdoc opt">,</span>
            <span class="string">&quot;net.Corp.MyApp&quot;</span><span class="gtkdoc opt">,</span>              <span class="comment">/* bus name */</span>
            <span class="string">&quot;/net/Corp/MyApp/SomeFrobber&quot;</span><span class="gtkdoc opt">,</span> <span class="comment">/* object */</span>
            NULL<span class="gtkdoc opt">,</span>                          <span class="comment">/* GCancellable* */</span>
            <span class="gtkdoc opt">&amp;</span>error<span class="gtkdoc opt">);</span>
<span class="comment">/* do stuff with proxy */</span>
<span class="function"><a href="../gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span> <span class="gtkdoc opt">(</span>proxy<span class="gtkdoc opt">);</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
      Instead of using the generic <a class="link" href="GDBusProxy.html" title="GDBusProxy"><span class="type">GDBusProxy</span></a> facilities, one can use
      the generated methods such as
      <code class="function"><code class="function">my_app_frobber_call_hello_world()</code></code> to invoke
      the <code class="function">net.Corp.MyApp.Frobber.HelloWorld()</code>
      D-Bus method, connect to the
      <code class="function">::notification</code> GObject signal to receive
      the <code class="function">net.Corp.MyApp.Frobber::Notication</code>
      D-Bus signal and get/set the
      <em class="parameter"><code>net.Corp.MyApp.Frobber:Verbose</code></em> D-Bus
      Property using either the GObject property
      <em class="parameter"><code>:verbose</code></em> or the
      <code class="function"><code class="function">my_app_get_verbose()</code></code> and
      <code class="function"><code class="function">my_app_set_verbose()</code></code> methods. Use the
      standard <a href="../gobject-The-Base-Object-Type.html#GObject-notify"><span class="type">“notify”</span></a> signal to listen to property changes.
    </p>
<p>
      Note that all property access is via <a class="link" href="GDBusProxy.html" title="GDBusProxy"><span class="type">GDBusProxy</span></a>'s
      property cache so no I/O is ever done when reading properties.
      Also note that setting a property will cause the
      <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties" target="_top">org.freedesktop.DBus.Properties.Set</a> method to be
      called on the remote object. This call, however, is asynchronous
      so setting a property won't block. Further, the change is
      delayed and no error checking is possible.
    </p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.4.26.7.10.11"></a><h3>Server-side usage</h3>
<p>
      The generated <span class="type">MyAppFrobber</span> interface is designed so
      it is easy to implement it in a <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a>
      subclass. For example, to handle
      <code class="function"><code class="function">HelloWorld()</code></code> method invocations, set the
      vfunc for <code class="function"><code class="function">handle_hello_hello_world()</code></code> in the
      <span class="type">MyAppFrobberIface</span> structure. Similary, to handle
      the <em class="parameter"><code>net.Corp.MyApp.Frobber:Verbose</code></em>
      property override the <em class="parameter"><code>:verbose</code></em> <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a>
      property from the subclass. To emit a signal, use
      e.g. <code class="function"><code class="function">my_app_emit_signal()</code></code> or
      <a href="../gobject-Signals.html#g-signal-emit-by-name"><code class="function">g_signal_emit_by_name()</code></a>.
    </p>
<p>
      Instead of subclassing, it is often easier to use the generated
      <span class="type">MyAppFrobberSkeleton</span> subclass. To handle incoming
      method calls, use <code class="function"><a href="../gobject-Signals.html#g-signal-connect"><code class="function">g_signal_connect()</code></a></code> with
      the <code class="function">::handle-*</code> signals and instead of
      overriding <a href="../gobject-The-Base-Object-Type.html#GObject-struct"><span class="type">GObject</span></a>'s
      <code class="function"><code class="function">get_property()</code></code> and
      <code class="function"><code class="function">set_property()</code></code> vfuncs, use
      <a href="../gobject-The-Base-Object-Type.html#g-object-get"><code class="function">g_object_get()</code></a> and
      <a href="../gobject-The-Base-Object-Type.html#g-object-set"><code class="function">g_object_set()</code></a> or the generated property
      getters and setters (the generated class has an internal
      property bag implementation).
    </p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="gtkdoc kwb">static</span> gboolean
<span class="function">on_handle_hello_world</span> <span class="gtkdoc opt">(</span>MyAppFrobber           <span class="gtkdoc opt">*</span>interface<span class="gtkdoc opt">,</span>
                       GDBusMethodInvocation  <span class="gtkdoc opt">*</span>invocation<span class="gtkdoc opt">,</span>
                       <span class="gtkdoc kwb">const</span> gchar            <span class="gtkdoc opt">*</span>greeting<span class="gtkdoc opt">,</span>
                       gpointer                user_data<span class="gtkdoc opt">)</span>
<span class="gtkdoc opt">{</span>
  <span class="keyword">if</span> <span class="gtkdoc opt">(</span><span class="function"><a href="../glib-String-Utility-Functions.html#g-strcmp0">g_strcmp0</a></span> <span class="gtkdoc opt">(</span>greeting<span class="gtkdoc opt">,</span> <span class="string">&quot;Boo&quot;</span><span class="gtkdoc opt">) !=</span> <span class="number">0</span><span class="gtkdoc opt">)</span>
    <span class="gtkdoc opt">{</span>
      gchar <span class="gtkdoc opt">*</span>response<span class="gtkdoc opt">;</span>
      response <span class="gtkdoc opt">=</span> <span class="function"><a href="../glib-String-Utility-Functions.html#g-strdup-printf">g_strdup_printf</a></span> <span class="gtkdoc opt">(</span><span class="string">&quot;Word! You said `%s&apos;.&quot;</span><span class="gtkdoc opt">,</span> greeting<span class="gtkdoc opt">);</span>
      <span class="function">my_app_complete_hello_world</span> <span class="gtkdoc opt">(</span>interface<span class="gtkdoc opt">,</span> invocation<span class="gtkdoc opt">,</span> response<span class="gtkdoc opt">);</span>
      <span class="function"><a href="../glib-Memory-Allocation.html#g-free">g_free</a></span> <span class="gtkdoc opt">(</span>response<span class="gtkdoc opt">);</span>
    <span class="gtkdoc opt">}</span>
  <span class="keyword">else</span>
    <span class="gtkdoc opt">{</span>
      <span class="function"><a href="GDBusMethodInvocation.html#g-dbus-method-invocation-return-error">g_dbus_method_invocation_return_error</a></span> <span class="gtkdoc opt">(</span>invocation<span class="gtkdoc opt">,</span>
                 MY_APP_ERROR<span class="gtkdoc opt">,</span>
                 MY_APP_ERROR_NO_WHINING<span class="gtkdoc opt">,</span>
                 <span class="string">&quot;Hey, %s, there will be no whining!&quot;</span><span class="gtkdoc opt">,</span>
                 <span class="function"><a href="GDBusMethodInvocation.html#g-dbus-method-invocation-get-sender">g_dbus_method_invocation_get_sender</a></span> <span class="gtkdoc opt">(</span>invocation<span class="gtkdoc opt">));</span>
    <span class="gtkdoc opt">}</span>
  <span class="keyword">return</span> TRUE<span class="gtkdoc opt">;</span>
<span class="gtkdoc opt">}</span>

  <span class="gtkdoc opt">[...]</span>

  interface <span class="gtkdoc opt">=</span> <span class="function">my_app_frobber_skeleton_new</span> <span class="gtkdoc opt">();</span>
  <span class="function">my_app_frobber_set_verbose</span> <span class="gtkdoc opt">(</span>interface<span class="gtkdoc opt">,</span> TRUE<span class="gtkdoc opt">);</span>

  <span class="function"><a href="../gobject-Signals.html#g-signal-connect">g_signal_connect</a></span> <span class="gtkdoc opt">(</span>interface<span class="gtkdoc opt">,</span>
                    <span class="string">&quot;handle-hello-world&quot;</span><span class="gtkdoc opt">,</span>
                    <span class="function"><a href="../gobject-Closures.html#G-CALLBACK:CAPS">G_CALLBACK</a></span> <span class="gtkdoc opt">(</span>on_handle_hello_world<span class="gtkdoc opt">),</span>
                    some_user_data<span class="gtkdoc opt">);</span>

  <span class="gtkdoc opt">[...]</span>

  error <span class="gtkdoc opt">=</span> NULL<span class="gtkdoc opt">;</span>
  <span class="keyword">if</span> <span class="gtkdoc opt">(!</span><span class="function"><a href="GDBusInterfaceSkeleton.html#g-dbus-interface-skeleton-export">g_dbus_interface_skeleton_export</a></span> <span class="gtkdoc opt">(</span><span class="function">G_DBUS_INTERFACE_SKELETON</span> <span class="gtkdoc opt">(</span>interface<span class="gtkdoc opt">),</span>
                                         connection<span class="gtkdoc opt">,</span>
                                         <span class="string">&quot;/path/of/dbus_object&quot;</span><span class="gtkdoc opt">,</span>
                                         <span class="gtkdoc opt">&amp;</span>error<span class="gtkdoc opt">))</span>
    <span class="gtkdoc opt">{</span>
      <span class="comment">/* handle error */</span>
    <span class="gtkdoc opt">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
      To facilitate atomic changesets (multiple properties changing at
      the same time), <a href="../gobject-The-Base-Object-Type.html#GObject-notify"><span class="type">“notify”</span></a> signals are queued up when
      received. The queue is drained in an idle handler (which is called from the
      <a href="../glib-The-Main-Event-Loop.html#g-main-context-push-thread-default">thread-default main loop</a>
      of the thread where the skeleton object was
      contructed) and will cause emissions of the <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties" target="_top">org.freedesktop.DBus.Properties::PropertiesChanged</a>
      signal with all the properties that have changed. Use
      <a class="link" href="GDBusInterfaceSkeleton.html#g-dbus-interface-skeleton-flush" title="g_dbus_interface_skeleton_flush ()"><code class="function">g_dbus_interface_skeleton_flush()</code></a> or
      <a class="link" href="GDBusObjectSkeleton.html#g-dbus-object-skeleton-flush" title="g_dbus_object_skeleton_flush ()"><code class="function">g_dbus_object_skeleton_flush()</code></a> to empty the queue
      immediately. Use <a href="../gobject-The-Base-Object-Type.html#g-object-freeze-notify"><code class="function">g_object_freeze_notify()</code></a> and
      <a href="../gobject-The-Base-Object-Type.html#g-object-thaw-notify"><code class="function">g_object_thaw_notify()</code></a> for atomic changesets if on a different
      thread.
    </p>
</div>
</div>
<div class="refsect1">
<a name="id-1.4.26.7.11"></a><h2>C Type Mapping</h2>
<p>
    Scalar types
    (type-strings
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</a>,
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-BYTE:CAPS">'y'</a>,
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-INT16:CAPS">'n'</a>,
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-UINT16:CAPS">'q'</a>,
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-INT32:CAPS">'i'</a>,
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-UINT32:CAPS">'u'</a>,
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-INT64:CAPS">'x'</a>,
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-UINT64:CAPS">'t'</a> and
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-DOUBLE:CAPS">'d'</a>)
    ),
    strings (type-strings
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-STRING:CAPS">'s'</a>,
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</a>,
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</a> and
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</a>) and
    arrays of string (type-strings
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</a>,
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</a> and
    <a href="../glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</a>)
    are mapped to the natural types,
    e.g. <a href="../glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a>, <a href="../glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>, <a href="../glib-Basic-Types.html#gint"><span class="type">gint</span></a>, <a href="../gobject-Standard-Parameter-and-Value-Types.html#gchararray">gchar*</a>,
    <a href="../glib-String-Utility-Functions.html#GStrv">gchar**</a> and
    so on. Everything else is mapped to the <a href="../glib-GVariant.html#GVariant"><span class="type">GVariant</span></a>
    type.
  </p>
<p>
    This automatic mapping can be turned off by using the annotation
    <code class="literal">org.gtk.GDBus.C.ForceGVariant</code> - if used then a
    <a href="../glib-GVariant.html#GVariant"><span class="type">GVariant</span></a> is always exchanged instead of the
    corresponding native C type. This annotation may be convenient to
    use when using
    bytestrings (type-string <a href="../glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</a>)
    for data that could have embedded NUL bytes.
  </p>
</div>
<div class="refsect1">
<a name="gdbus-code-stability"></a><h2>Stability Guarantees</h2>
<p>
    The generated C functions are guaranteed to not change their ABI
    that is, if a method, signal or property does not change its
    signature in the introspection XML, the generated C functions will
    not change its C ABI either. The ABI of the generated instance and
    class structures will be preserved as well.
  </p>
<p>
    The ABI of the generated <a href="../gobject-Type-Information.html#GType"><span class="type">GType</span></a>s will be preserved only if
    the <code class="literal">org.gtk.GDBus.Since</code> annotation is used
    judiciously — this is because the VTable for the <a href="/home/mclasen/gnome/share/gtk-doc/html/gobject/GTypeModule.html"><span class="type">GInterface</span></a>
    relies on functions pointers for signal handlers. Specifically, if
    a D-Bus method, property or signal or is added to a D-Bus
    interface, then ABI of the generated <a href="/home/mclasen/gnome/share/gtk-doc/html/gobject/GTypeModule.html"><span class="type">GInterface</span></a> type is preserved
    if, and only if, each added method, property signal is annotated
    with they <code class="literal">org.gtk.GDBus.Since</code> annotation using
    a greater version number than previous versions.
  </p>
<p>
    The generated C code currently happens to be annotated with <a class="ulink" href="http://www.gtk.org/gtk-doc/" target="_top">gtk-doc</a> / <a class="ulink" href="https://wiki.gnome.org/Projects/GObjectIntrospection" target="_top">GObject
    Introspection</a> comments / annotations. The layout and
    contents might change in the future so no guarantees about
    e.g. <code class="literal">SECTION</code> usage etc. is given.
  </p>
<p>
    While the generated Docbook for D-Bus interfaces isn't expected to
    change, no guarantees are given at this point.
  </p>
<p>
    It is important to note that the generated code should not be
    checked into revision control systems, nor it should be included
    in distributed source archives.
  </p>
</div>
<div class="refsect1">
<a name="id-1.4.26.7.13"></a><h2>Bugs</h2>
<p>
    Please send bug reports to either the distribution bug tracker
    or the upstream bug tracker at
    <a class="ulink" href="https://bugzilla.gnome.org/enter_bug.cgi?product=glib" target="_top">https://bugzilla.gnome.org/enter_bug.cgi?product=glib</a>.
  </p>
</div>
<div class="refsect1">
<a name="id-1.4.26.7.14"></a><h2>See also</h2>
<p>
    <span class="citerefentry"><span class="refentrytitle">gdbus</span>(1)</span>
  </p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.26.1</div>
</body>
</html>